<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>OSClisten</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="OSCinit.html" title="OSCinit" />
    <link rel="next" href="OSCsend.html" title="OSCsend" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">OSClisten</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="OSCinit.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="OSCsend.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="OSClisten"></a>
      <div class="titlepage"></div>
      <a id="IndexOSClisten" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">OSClisten</span>
        </h2>
        <p>OSClisten — 
      Listen for OSC messages to a particular path.
          </p>
      </div>
      <div class="refsect1">
        <a id="idp129741440"></a>
        <h2>Description</h2>
        <p>
      On each k-cycle looks to see if an OSC message has been send to
      a given path of a given type.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp129782800"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">kans <span class="command"><strong>OSClisten</strong></span> ihandle, idest, itype [, xdata1, xdata2, ...]</pre>
      </div>
      <div class="refsect1">
        <a id="idp129784816"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>ihandle</em></span>
      -- a handle returned by an earlier call to OSCinit, to associate
      OSClisten with a particular port number.
    </p>
        <p>
      <span class="emphasis"><em>idest</em></span>
      -- a string that is the destination address.  This takes the
      form of a file name with directories.  Csound uses this address
      to decide if messages are meant for csound.
    </p>
        <p>
      <span class="emphasis"><em>itype</em></span>
      -- a string that indicates the types of the optional arguments
      that are to be read.  The string can contain the characters
      "cdfhis" which stand for character, double, float, 64-bit integer,
      32-bit integer, and string. All types other than 's' require a
      k-rate variable, while 's' requires a string variable.
    </p>
        <p> A handler is inserted into the listener (see OSCinit) to
      intercept messages of this pattern.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp129789200"></a>
        <h2>Performance</h2>
        <p>
      <span class="emphasis"><em>kans</em></span> -- set to 1 if a new message was
      received, or zero if not. If multiple messages are received in
      a single control period, the messages are buffered, and OSClisten
      can be called again until zero is returned.
    </p>
        <p>
      If there was a message the <span class="emphasis"><em>xdata</em></span> variables
      are set to the incoming values, as interpretted by the
      <span class="emphasis"><em>itype</em></span> parameter.
      Note that although the <span class="emphasis"><em>xdata</em></span> variables are on
      the right of an operation they are actually outputs, and so must be
      variables of type k, gk, S, or gS, and may need to be declared with
      init, or = in the case of string variables, before calling OSClisten.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp129793136"></a>
        <h2>Example</h2>
        <p>
      The example shows a pair of floating point numbers being received
      on port 7770.
    </p>
        <div class="informalexample">
          <pre class="programlisting">
  <span class="ohdr">sr</span> <span class="op">=</span> 44100
  <span class="ohdr">ksmps</span> <span class="op">=</span> 100
  <span class="ohdr">nchnls</span> <span class="op">=</span> 2

  gihandle <span class="opc">OSCinit</span> 7770

  <span class="oblock">instr</span>   1
    kf1 <span class="opc">init</span> 0
    kf2 <span class="opc">init</span> 0
nxtmsg:
    kk  <span class="opc">OSClisten</span> gihandle, "/foo/bar", "ff", kf1, kf2
if (kk <span class="opc">==</span> 0) goto ex
    <span class="opc">printk</span> 0,kf1
    <span class="opc">printk</span> 0,kf2
    <span class="opc">kgoto</span> nxtmsg
ex:
  <span class="oblock">endin</span>
        </pre>
        </div>
        <p>
      Below are two .csd files which demonstrate the usage of the OSC opcodes. They use the files <a class="ulink" href="examples/OSCmidisend.csd" target="_top"><em class="citetitle">OSCmidisend.csd</em></a> and <a class="ulink" href="examples/OSCmidircv.csd" target="_top"><em class="citetitle">OSCmidircv.csd</em></a>.

      </p>
        <div class="example">
          <a id="idp129808336"></a>
          <p class="title">
            <strong>Example 569. Example of the OSC opcodes.</strong>
          </p>
          <div class="example-contents">
            <p>The following two .csd files demonstrate the usage of the OSC opcodes in csound. The first file, <a class="ulink" href="examples/OSCmidisend.csd" target="_top"><em class="citetitle">OSCmidisend.csd</em></a>, transforms received real-time MIDI messages into OSC data. The second file, <a class="ulink" href="examples/OSCmidircv.csd" target="_top"><em class="citetitle">OSCmidircv.csd</em></a>, can take these OSC messages, and intrepret them to generate sound from note messages, and store controller values. It will use controller number 7 to control volume. Note that these files are designed to be on the same machine, but if a different host address (in the IPADDRESS macro) is used, they can be separate machines on a network, or connected through the internet.</p>
            <p>CSD file to send OSC messages:</p>
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">; Audio out   Audio in</span>
-odac           -iadc    <span class="comment">;;;RT audio I/O</span>
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>

  <span class="ohdr">sr</span>	    <span class="op">=</span>  44100
  <span class="ohdr">ksmps</span>	    <span class="op">=</span>  128
  <span class="ohdr">nchnls</span>    <span class="op">=</span>  1

<span class="comment">; Example by David Akbari 2007</span>
<span class="comment">; Modified by Jonathan Murphy</span>
<span class="comment">; Use this file to generate OSC events for OSCmidircv.csd</span>

<span class="omacro">#define</span> IPADDRESS	# "localhost" #
<span class="omacro">#define</span> PORT 		# 47120 #

<span class="opc">turnon</span> 1000


    <span class="oblock">instr</span>	1000

  kst, kch, kd1, kd2  <span class="opc">midiin</span>

  <span class="opc">OSCsend</span>   kst<span class="op">+</span>kch<span class="op">+</span>kd1<span class="op">+</span>kd2, $IPADDRESS, $PORT, "<span class="op">/</span>midi", "iiii", kst, kch, kd1, kd2

    <span class="oblock">endin</span>


<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>
<span class="stamnt">f</span> 0 3600  <span class="comment">;Dummy f-table</span>
<span class="stamnt">e</span>
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
            <p>CSD file to receive OSC messages:</p>
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">; Audio out   Audio in</span>
-odac           -iadc    <span class="comment">;;;RT audio I/O</span>
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>

  <span class="ohdr">sr</span>	    <span class="op">=</span>  44100
  <span class="ohdr">ksmps</span>	    <span class="op">=</span>  128
  <span class="ohdr">nchnls</span>    <span class="op">=</span>  1

<span class="comment">; Example by Jonathan Murphy and Andres Cabrera 2007</span>
<span class="comment">; Use file OSCmidisend.csd to generate OSC events for this file</span>

  <span class="ohdr">0dbfs</span>	    <span class="op">=</span>  1

  gilisten  <span class="opc">OSCinit</span>   47120

  gisin	    <span class="ohdr">ftgen</span>     1, 0, 16384, 10, 1
  givel	    <span class="ohdr">ftgen</span>     2, 0, 128, <span class="op">-</span>2, 0
  gicc	    <span class="ohdr">ftgen</span>     3, 0, 128, <span class="op">-</span>7, 100, 128, 100  <span class="comment">;Default all controllers to 100</span>
 
<span class="comment">;Define scale tuning</span>
  giji_12   <span class="ohdr">ftgen</span>     202, 0, 32, <span class="op">-</span>2, 12, 2, 256, 60, 1, 16<span class="op">/</span>15, 9<span class="op">/</span>8, 6<span class="op">/</span>5, 5<span class="op">/</span>4, 4<span class="op">/</span>3, 7<span class="op">/</span>5, \
                               3<span class="op">/</span>2, 8<span class="op">/</span>5, 5<span class="op">/</span>3, 9<span class="op">/</span>5, 15<span class="op">/</span>8, 2

<span class="omacro">#define</span> DEST #"<span class="op">/</span>midi"#
<span class="comment">; Use controller number 7 for volume</span>
<span class="omacro">#define</span> VOL #7#

<span class="opc">turnon</span> 1000


    <span class="oblock">instr</span>   1000

  kst	    <span class="opc">init</span>      0
  kch	    <span class="opc">init</span>      0
  kd1	    <span class="opc">init</span>      0
  kd2	    <span class="opc">init</span>      0

<span class="olabel">next</span><span class="op">:</span>

  kk	    <span class="opc">OSClisten</span>	gilisten, $DEST, "iiii", kst, kch, kd1, kd2

<span class="octrl">if</span> (kk <span class="op">==</span> 0) <span class="octrl">goto</span> <span class="olabel">done</span>

<span class="opc">printks</span> "kst <span class="op">=</span> <span class="op">%</span>i, kch <span class="op">=</span> <span class="op">%</span>i, kd1 <span class="op">=</span> <span class="op">%</span>i, kd2 <span class="op">=</span> <span class="op">%</span>i\\n", \
         0, kst, kch, kd1, kd2

<span class="octrl">if</span> (kst <span class="op">==</span> 176) then
<span class="comment">;Store controller information in a table</span>
	    <span class="opc">tablew</span>    kd2, kd1, gicc
<span class="octrl">endif</span>  

<span class="octrl">if</span> (kst <span class="op">==</span> 144) then
<span class="comment">;Process noteon and noteoff messages.</span>
  kkey	    <span class="op">=</span>  kd1
  kvel	    <span class="op">=</span>  kd2
  kcps	    <span class="opc">cpstun</span>    kvel, kkey, giji_12
  kamp	    <span class="op">=</span>  kvel<span class="op">/</span>127

<span class="octrl">if</span> (kvel <span class="op">==</span> 0) then
	    <span class="opc">turnoff2</span>  1001, 4, 1
<span class="octrl">elseif</span> (kvel <span class="op">&gt;</span> 0) then
	    <span class="opc">event</span>     "i", 1001, 0, <span class="op">-</span>1, kcps, kamp
<span class="octrl">endif</span>
<span class="octrl">endif</span>

	<span class="octrl">kgoto</span>	<span class="olabel">next</span>  <span class="comment">;Process all events in queue</span>

<span class="olabel">done</span><span class="op">:</span>
    <span class="oblock">endin</span>



    <span class="oblock">instr</span> 1001   <span class="comment">;Simple instrument</span>

  icps	    <span class="opc">init</span>      p4
  kvol	    <span class="opc">table</span>     $VOL, gicc  <span class="comment">;Read MIDI volume from controller table</span>
  kvol	    <span class="op">=</span>  kvol<span class="op">/</span>127

  aenv     <span class="opc">linsegr</span>    0, .003, p5, 0.03, p5 <span class="op">*</span> 0.5, 0.3, 0
  aosc	    <span class="opc">oscil</span>     aenv, icps, gisin

	    <span class="opc">out</span>	      aosc <span class="op">*</span> kvol
    <span class="oblock">endin</span>


<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>
<span class="stamnt">f</span> 0 3600  <span class="comment">;Dummy f-table</span>
<span class="stamnt">e</span>
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
          </div>
        </div>
        <p><br class="example-break" />
    </p>
      </div>
      <div class="refsect1">
        <a id="idp129814528"></a>
        <h2>See Also</h2>
        <p>
        <a class="link" href="OSCsend.html" title="OSCsend"><em class="citetitle">OSCsend</em></a>,
        <a class="link" href="OSCinit.html" title="OSCinit"><em class="citetitle">OSCinit</em></a>
      </p>
        <p> More information on this opcode: <a class="ulink" href="http://www.youtube.com/watch?v=JX1C3TqP_9Y" target="_top"><em class="citetitle">http://www.youtube.com/watch?v=JX1C3TqP_9Y</em></a>  , made by Andrés Cabrera </p>
      </div>
      <div class="refsect1">
        <a id="idp129818928"></a>
        <h2>Credits</h2>
        <p>
      </p>
        <table border="0" summary="Simple list" class="simplelist">
          <tr>
            <td>Author: John ffitch</td>
          </tr>
          <tr>
            <td>2005</td>
          </tr>
          <tr>
            <td>Examples by: David Akbari, Andrés Cabrera and Jonathan Murphy 2007</td>
          </tr>
        </table>
        <p>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="OSCinit.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="OSCsend.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">OSCinit </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> OSCsend</td>
        </tr>
      </table>
    </div>
  </body>
</html>
